package com.example.happybirthday // 定义当前文件所属的包名。这是 Kotlin 文件在项目中的位置标识。

import android.os.Bundle // 导入 Android Bundle 类，用于在 Activity 之间传递数据或保存状态。
import androidx.activity.ComponentActivity // 导入 ComponentActivity，这是使用 Jetpack Compose 的 Activity 基类。你的主屏幕 Activity 需要继承它。
import androidx.activity.compose.setContent // 导入 setContent 函数，这是 ComponentActivity 的一个扩展函数，用于在 Activity 中设置 Compose UI 内容。
import androidx.activity.enableEdgeToEdge // 导入 enableEdgeToEdge 函数，用于让应用内容延伸到屏幕边缘（状态栏和导航栏下方），提供沉浸式体验。
import androidx.compose.foundation.layout.Arrangement // 导入 Arrangement，用于控制 Column 或 Row 中子元素的排列方式和间距。
import androidx.compose.foundation.layout.Column // 导入 Column 可组合函数，用于将其内部的子元素垂直排列。
import androidx.compose.foundation.layout.Row // 导入 Row 可组合函数，用于水平排列子元素 (虽然在此代码中未使用，但通常与 Column 一起导入，因为它们是基本的布局容器)。
import androidx.compose.foundation.layout.fillMaxSize // 导入 fillMaxSize Modifier，用于使 Composable 填充其父容器的最大尺寸。
import androidx.compose.foundation.layout.padding // 导入 padding Modifier，用于给 Composable 添加内边距。
import androidx.compose.material3.MaterialTheme // 导入 MaterialTheme，用于应用 Material Design 主题（颜色、排版、形状等）。所有 Material Design 组件都会继承这里定义的主题属性。
import androidx.compose.material3.Scaffold // 导入 Scaffold，用于实现 Material Design 布局结构（如顶部应用栏、底部导航栏、浮动按钮等，在此代码中未使用）。
import androidx.compose.material3.Surface // 导入 Surface 可组合函数，用于创建一个 Material Design 风格的表面，通常用于背景或卡片等。它会自动应用主题的颜色和形状。
import androidx.compose.material3.Text // 导入 Text 可组合函数，用于显示文本。
import androidx.compose.runtime.Composable // 导入 @Composable 注解，这是 Compose 的核心注解，标记一个函数是可组合函数，可以用于构建 UI。
import androidx.compose.ui.Alignment // 导入 Alignment，用于控制 Column 或 Row 中子元素的对齐方式。
import androidx.compose.ui.Modifier // 导入 Modifier 类，用于修饰或增强 Composable 的外观和行为。Modifier 可以链式调用。
import androidx.compose.ui.res.painterResource // 导入 painterResource 函数，用于从 Android 资源中加载图片（如 drawable 文件夹）。
import androidx.compose.ui.text.style.TextAlign // 导入 TextAlign，用于设置文本在自身宽度范围内的对齐方式（左对齐、居中、右对齐等）。
import androidx.compose.ui.tooling.preview.Preview // 导入 @Preview 注解，用于在 Android Studio 的 Design 视图中预览 Composable，无需运行应用。
import androidx.compose.ui.unit.dp // 导入 dp 单位，表示屏幕密度无关像素（Density-independent Pixels），用于指定尺寸和间距，确保在不同屏幕密度下显示效果一致。
import androidx.compose.ui.unit.sp // 导入 sp 单位，表示可缩放像素（Scale-independent Pixels），通常用于字体大小，会根据用户设置的字体大小进行缩放。
import com.example.happybirthday.ui.theme.HappyBirthdayTheme // 导入应用自定义的主题文件。
import androidx.compose.foundation.Image // 导入 Image 可组合函数，用于显示图片。
import androidx.compose.foundation.layout.Box // 导入 Box 可组合函数，用于堆叠子元素（后添加的在上面），或用于给单个子元素设置对齐方式。
import androidx.compose.ui.layout.ContentScale // 导入 ContentScale，用于控制图片在 Image 容器中的缩放和裁剪方式。
import androidx.compose.ui.res.stringResource // 导入 stringResource 函数，用于从 Android 资源中加载字符串（如 strings.xml 文件）。

// 你在代码中保留的关于 Compose 概念的注释，非常好的学习笔记！
/**
 * 摘要
 * Jetpack Compose 是用于构建 Android 界面的新款工具包。它使用更少的代码、强大的工具和直观的 Kotlin API，可以帮助您简化并加快 Android 界面开发。
 * 应用的界面 (UI) 就是您在屏幕上所看到的内容，包括文本、图片、按钮和许多其他类型的元素。
 * 可组合函数是 Compose 的基本构建块。可组合函数是用于描述界面中某一部分的函数。
 * 可组合函数带有 @Composable 注解；此注解可告知 Compose 编译器：此函数用于将数据转换为界面。
 * Compose 中的三个基本标准布局元素是 Column、Row, 和 Box。它们是接受可组合内容的可组合函数，因此您可以在其中放置项目。例如，Row 中的各个子项将彼此相邻地水平放置。
 */

// MainActivity 类，它是应用的入口点 Activity
class MainActivity : ComponentActivity() {
    // onCreate 方法，Activity 生命周期中的创建阶段。当 Activity 首次创建时调用。
    override fun onCreate(savedInstanceState: Bundle?) {
        // 调用父类的 onCreate 方法，完成 Activity 的基本初始化。
        super.onCreate(savedInstanceState)
        // 启用边缘到边缘显示，让内容可以绘制到状态栏和导航栏下方。
        enableEdgeToEdge()
        // setContent 是 ComponentActivity 的扩展函数，用于设置 Activity 的 Compose UI 内容。
        // 所有在 setContent lambda 内部定义的 Composable 都会成为 Activity 的根视图。
        setContent {
            // 应用自定义的 HappyBirthdayTheme 主题。所有在其内部的 Composable 都会继承这个主题的属性。
            HappyBirthdayTheme {
                // Surface 是一个 Material Design 容器，通常用于背景或卡片。
                Surface(
                    // Modifier 用于修饰 Surface。
                    modifier = Modifier.fillMaxSize(), // 使 Surface 填充其父容器（整个屏幕）的最大尺寸。
                    // 设置 Surface 的背景颜色为当前主题的背景色。
                    color = MaterialTheme.colorScheme.background
                ) {
                    // 调用 GreetingText 可组合函数，显示生日祝福信息。
                    // message 参数设置为硬编码的字符串 "生日快乐，斋藤飞鸟姐姐!"。
                    // from 参数设置为硬编码的字符串 "from fan"。
                    // GreetingText(message = "生日快乐，斋藤飞鸟姐姐!", from = "from fan")

                    // 调用 GreetingImage 可组合函数，显示带有背景图片的生日祝福界面。
                    // message 和 from 参数通过 stringResource 从 strings.xml 文件中加载。
                    GreetingImage(
                        message = stringResource(R.string.happy_birthday_text), // 从 strings.xml 加载 happy_birthday_text 字符串
                        from = stringResource(R.string.signature_text) // 从 strings.xml 加载 signature_text 字符串
                    )
                }
            }
        }
    }
}

// 你在代码中保留的关于 Composable 函数命名和规则的注释，非常有帮助！
/**
 * 可组合函数带有 @Composable 注解。所有可组合函数都必须带有此注解。此注解可告知 Compose 编译器：此函数用于将数据转换为界面。请注意，编译器是一种特殊的程序，它会接受您编写的代码，逐行查看，然后将其转换成计算机可以理解的指令（机器语言）。
 * 关于可组合函数的几点说明：
 * Jetpack Compose 是围绕可组合函数构建的。这些函数可让您以程序化方式定义应用的界面，只需描述应用界面的外观，而不必关注界面的构建过程。如需创建可组合函数，只需将 @Composable 注解添加到函数名称中即可。
 * 可组合函数可以接受一些实参，用来让应用逻辑描述或修改界面。在本例中，界面元素接受一个 String，以便在问候用户时称呼姓名。
 * 可组合函数名称
 * 不返回任何内容且带有 @Composable 注解的 Compose 函数必须使用 Pascal 命名法命名。Pascal 命名法是指一种命名惯例，采用这种命名法时，复合词中每个单词的首字母大写。Pascal 命名法与驼峰命名法之间的区别在于：在 Pascal 命名法中，所有单词的首字母都大写；而在驼峰命名法中，首字母可以是大写或小写。
 *
 * Compose 函数：
 * 必须是名词：DoneButton()MUST
 * 不能是动词或动词短语：DrawTextField()
 * 不能是名词性介词：TextFieldWithLink()
 * 不能是形容词：Bright()
 * 不能是副词：Outside()
 * 名词可以添加描述性形容词作为前缀：RoundIcon()
 */
@Composable // @Composable 注解标记这是一个可组合函数
fun Greeting(name: String, modifier: Modifier = Modifier) { // 函数名 Greeting，接收 name 和 modifier 参数
    Text( // 调用 Text 可组合函数显示文本
        text = "Hello $name!", // 设置文本内容
        modifier = modifier // 应用外部传入的 modifier
    )
}


// 你在代码中保留的关于 Text Composable 的注释
/**
 * 一个用于描述 Text 可组合项的 Compose 函数。
 *
 */
// @Composable 注解标记这是一个可组合函数，用于显示问候语和来源文本。
@Composable
fun GreetingText(
    message: String, // 接收一个 String 类型的 message 参数，用于显示主要文本（如生日祝福）。
    from: String, // 接收一个 String 类型的 from 参数，用于显示来源文本（如署名）。
    modifier: Modifier = Modifier // 接收一个 Modifier 参数，用于外部对这个 Composable 进行修饰，并设置默认值为一个空的 Modifier。
) {
    // Column 布局容器，用于将其内部的子元素垂直排列。
    Column(
        // verticalArrangement 参数控制子元素在垂直方向上的排列方式和间距。
        verticalArrangement = Arrangement.Center, // 设置子元素在垂直方向上居中排列。
        // modifier 参数用于修饰 Column 本身。
        modifier = modifier // 应用外部传入的 modifier。
            .padding(8.dp) // 在 Column 的内容周围添加 8 dp 的内边距。
    ) {
        // 第一个 Text 可组合函数，用于显示 message 文本。
        /**
         * “在 Kotlin 中，当调用函数时，我们可以使用具名参数 (Named Arguments) 的方式来传递参数，也就是使用 参数名 = 参数值 的语法。您在 Text 函数调用中看到的 text = message, fontSize = 70.sp 就是具名参数的应用。
         * 之所以不需要在调用时再次指明类型，是因为参数的类型已经在函数定义中明确声明了。Kotlin 编译器在编译时会根据你提供的参数名，去函数定义中找到对应的参数，并检查你传递的参数值的类型是否与函数定义中声明的参数类型一致。如果类型不匹配，编译器就会报错。
         * 具名参数在 Compose 中非常常用，因为它能显著提高代码的可读性，特别是当 Composable 函数有很多参数时。它也使得跳过带默认值的参数变得非常方便。”
         */
        Text(
            text = message, // 设置文本内容为 message 参数的值。
            fontSize = 70.sp, // 设置字体大小为 70 sp。
            lineHeight = 80.sp, // 设置行高为 80 sp。
            textAlign = TextAlign.Center // 设置文本在自身宽度范围内的对齐方式为居中。
            // 注意：这里 Text 函数的参数之间都使用了逗号 "," 进行分隔。
        )

        // 第二个 Text 可组合函数，用于显示 from 文本。
        Text(
            text = from, // 设置文本内容为 from 参数的值。
            fontSize = 36.sp, // 设置字体大小为 36 sp。
            // modifier 参数用于修饰这个 Text 本身。
            modifier = modifier // 应用外部传入的 modifier。
                .padding(16.dp) // 在这个 Text 的内容周围添加 16 dp 的内边距。
                // align Modifier 是 ColumnScope 或 RowScope 的扩展函数，用于在父容器 (这里是 Column) 中对齐这个子元素。
                .align(Alignment.CenterHorizontally) // 将这个 Text 在父容器 Column 中水平方向上居中对齐。
            // 注意：这里 Text 函数的参数之间都使用了逗号 "," 进行分隔。
        )
    }
    // 注意：GreetingText 函数的顶层只有一个 Column 容器。
}

// @Composable 注解标记这是一个可组合函数，用于显示带有背景图片的生日祝福界面。
@Composable
fun GreetingImage(
    message: String, // 接收一个 String 类型的 message 参数，用于显示主要文本。
    from: String, // 接收一个 String 类型的 from 参数，用于显示来源文本。
    modifier: Modifier = Modifier // 接收一个 Modifier 参数，用于外部对这个 Composable 进行修饰，并设置默认值为一个空的 Modifier。
) {
    // 使用 painterResource 从 drawable 资源中加载名为 "asuka" 的图片。
    val image = painterResource(R.drawable.asuka)

    // Box 布局容器，用于堆叠子元素。后添加的子元素会显示在前面子元素的上面。
    Box(modifier = modifier) { // 应用外部传入的 modifier 到 Box。
        // Image 可组合函数，用于显示图片。
        Image(
            painter = image, // 设置要显示的图片，使用上面加载的 painterResource。
            contentDescription = null, // 设置图片的描述，用于无障碍功能。null 表示这张图片是装饰性的，不需要读屏器描述。
            contentScale = ContentScale.Crop, // 设置图片在 Image 容器中的缩放和裁剪方式。Crop 会保持图片的宽高比，并填充整个容器，超出部分会被裁剪。
            alpha = 0.8f // 设置图片的透明度，0.0f 表示完全透明，1.0f 表示完全不透明。这里设置为 0.8f 使图片稍微透明。
        )

        // 调用 GreetingText 可组合函数，显示文本内容。它会堆叠在 Image 上面。
        GreetingText(
            message = message, // 将外部传入的 message 参数传递给 GreetingText。
            from = from, // 将外部传入的 from 参数传递给 GreetingText。
            // modifier 参数用于修饰 GreetingText。
            modifier = Modifier
                // align Modifier 是 BoxScope 的扩展函数，用于在父容器 (这里是 Box) 中对齐这个子元素。
                .align(Alignment.BottomCenter) // 将 GreetingText 在父容器 Box 中水平居中并底部对齐。

        )
    }
}


// 你在代码中保留的关于 Preview 和 Composable 的注释
/**
 * Jetpack Compose 是用于构建 Android 界面的新款工具包。Compose 使用更少的代码、强大的工具和直观的 Kotlin 功能，可以帮助您简化并加快 Android 界面开发。借助 Compose，您可以通过定义一组函数来构建界面，这些函数称为可组合函数，它们会接受数据并描述界面元素。
 *
 * 可组合函数
 * 在 Compose 中，可组合函数是界面的基本构建块。
 * 可组合函数：
 * 描述界面中的某一部分。
 * 不会返回任何内容。
 * 接受一些输入并生成屏幕上显示的内容。
 *
 * 使用 @Preview 注解添加到 BirthdayCardPreview() 函数中的代码仅用于在 Android Studio 的 Design 窗格中进行预览。这些更改不会反映在应用中。
 *
 */
// @Preview 注解用于在 Android Studio 的 Design 视图中预览这个 Composable。
@Preview(showBackground = true) // showBackground = true 会给预览添加一个背景，方便查看。
// @Composable 注解标记这是一个可组合函数（Preview 函数本身也需要是 Composable）。
@Composable
fun BirthdayCardPreview() {
    // 在预览中应用 HappyBirthdayTheme 主题，这样预览效果会包含主题样式。
    HappyBirthdayTheme {
        // 注释掉的 Greeting 预览
        //Greeting("斋藤飞鸟")

        // 注释掉的 GreetingText 预览
        // GreetingText(message = "生日快乐\n斋藤飞鸟\n姐姐!", from = "from fan")

        // 调用 GreetingImage 函数进行预览。
        // message 和 from 参数通过 stringResource 从 strings.xml 文件中加载，用于预览。
        GreetingImage(
            message = stringResource(R.string.happy_birthday_text), // 从 strings.xml 加载 happy_birthday_text 字符串用于预览
            from = stringResource(R.string.signature_text) // 从 strings.xml 加载 signature_text 字符串用于预览
        )
    }
}
